.\"
.\" Copyright (c) 2014 Rui Paulo
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 3, 2025
.Dt GPIO 3
.Os
.Sh NAME
.Nm gpio_open ,
.Nm gpio_close
.Nd "library to handle GPIO pins"
.Sh LIBRARY
.Lb libgpio
.Sh SYNOPSIS
.In sys/types.h
.In libgpio.h
.Ft "gpio_handle_t"
.Fn gpio_open "unsigned int unit"
.Ft "gpio_handle_t"
.Fn gpio_open_device "const char *device"
.Ft void
.Fn gpio_close "gpio_handle_t handle"
.Ft int
.Fn gpio_pin_list "gpio_handle_t handle" "gpio_config_t **pcfgs"
.Ft int
.Fn gpio_pin_config "gpio_handle_t handle" "gpio_config_t *cfg"
.Ft int
.Fn gpio_pin_set_name "gpio_handle_t handle" "gpio_pin_t pin" "char *name"
.Ft int
.Fn gpio_pin_set_flags "gpio_handle_t handle" "gpio_config_t *cfg"
.Ft gpio_value_t
.Fn gpio_pin_get "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_set "gpio_handle_t handle" "gpio_pin_t pin" "gpio_value_t value"
.Ft int
.Fn gpio_pin_toggle "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_low "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_high "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_input "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_output "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_opendrain "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_pushpull "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_tristate "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_pullup "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_pulldown "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_invin "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_invout "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_pin_pulsate "gpio_handle_t handle" "gpio_pin_t pin"
.Ft int
.Fn gpio_configure_events "gpio_handle_t handle" "uint32_t report_type" "uint32_t fifo_size"
.Ft int
.Fn gpio_fileno "gpio_handle_t handle"
.Sh DESCRIPTION
The
.Nm libgpio
library provides an interface to configure GPIO pins.
The library operates with a
.Ft gpio_handle_t
opaque type which can be created with
.Fn gpio_open
or
.Fn gpio_open_device .
When no more GPIO operations are needed, this handle can be destroyed
with
.Fn gpio_close .
.Pp
To get a list of all available pins, one can call
.Fn gpio_pin_list .
This function takes a pointer to a
.Ft gpio_config_t
which is dynamically allocated.
This pointer should be freed with
.Xr free 3
when it is no longer necessary.
.Pp
The function
.Fn gpio_pin_config
retrieves the current configuration of a pin.
The pin number should be passed in via the
.Ft g_pin
variable which is part of the
.Ft gpio_config_t
structure.
.Pp
The function
.Fn gpio_pin_set_name
sets the name used to describe a pin.
.Pp
The function
.Fn gpio_pin_set_flags
configures a pin with the flags passed in by the
.Ft gpio_config_t
structure.
The pin number should also be passed in through the
.Ft g_pin
variable.
All other structure members will be ignored by this function.
The list of flags can be found in
.In sys/gpio.h .
.Pp
The get or set the state of a GPIO pin, the functions
.Fn gpio_pin_get
and
.Fn gpio_pin_set
are available, respectively.
To toggle the state, use
.Fn gpio_pin_toggle .
.Pp
The functions
.Fn gpio_pin_low
and
.Fn gpio_pin_high
are wrappers around
.Fn gpio_pin_set .
.Pp
The functions
.Fn gpio_pin_input ,
.Fn gpio_pin_output ,
.Fn gpio_pin_opendrain ,
.Fn gpio_pin_pushpull ,
.Fn gpio_pin_tristate ,
.Fn gpio_pin_pullup ,
.Fn gpio_pin_pulldown ,
.Fn gpio_pin_invin ,
.Fn gpio_pin_invout
and
.Fn gpio_pin_pulsate
are wrappers around
.Fn gpio_pin_set_flags .
.Pp
The function
.Fn gpio_configure_events
configures the interrupt report type and FIFO size for buffered
gpio interrupts.
The report type is specified by one of the following values:
.Bl -tag -width indent
.It Dv GPIO_EVENT_REPORT_DETAIL
Events are reported using
.Ft struct gpio_event_detail .
.It Dv GPIO_EVENT_REPORT_SUMMARY
Events are reported using
.Ft struct gpio_event_summary .
.El
.Pp
By default, the report type is
.Dv GPIO_EVENT_REPORT_DETAIL ,
with a default FIFO size of 2 * number of pins belonging to the
.Ft gpio_device_t
instance.
The FIFO argument is only meaningful when
.Fa report_type
is
.Dv GPIO_EVENT_REPORT_DETAIL .
The structures associated with each report type are defined in
.In sys/gpio.h .
This setting is tracked on a per device instance basis.
The FIFO size cannot be reduced below the default value,
nor can it be decreased after it has been increased.
If any pin on the device has already been configured for interrupts,
.Fn gpio_configure_events
fails and returns -1.
On success 0 is returned.
.Pp
The function
.Fn gpio_fileno
returns the file descriptor associated with the
.Ft gpio_handle_t
instance.
.Pp
File operations have the following semantics:
.Bl -tag -width "read (2)"
.It Xr read 2
Read one or more gpio interrupts that have occured
since the last successful
.Xr read 2 .
The results are placed into the output buffer
of the type previously established via
.Fn gpio_configure_events .
If there are no pending interrupts,
.Xr read 2
blocks until an interrupt occurs, unless
.Dv O_NONBLOCK
is set.
.It Xr poll 2
When receiving notification via
.Xr poll 2
or similar interfaces, the file descriptor becomes readable when
one or more gpio interrupts are pending.
.El
.Sh EXAMPLES
The following example shows how to configure pin 16 as output and then
drive it high:
.Bd -literal
#include <sys/types.h>
#include <err.h>
#include <libgpio.h>

gpio_handle_t handle;

handle = gpio_open(0);
if (handle == GPIO_INVALID_HANDLE)
	err(1, "gpio_open failed");
gpio_pin_output(handle, 16);
gpio_pin_high(handle, 16);
gpio_close(handle);
.Ed
.Pp
The following example shows how to get a configuration of a pin:
.Bd -literal
gpio_config_t cfg;

cfg.g_pin = 32;
gpio_pin_config(handle, &cfg);
.Ed
.Pp
The structure will contain the name of the pin and its flags.
.Sh SEE ALSO
.Xr gpiobus 4 ,
.Xr gpioctl 8
.Sh HISTORY
The
.Nm libgpio
library first appeared in
.Fx 11.0 .
.Sh AUTHORS
The
.Nm libgpio
library was implemented by
.An Rui Paulo Aq Mt rpaulo@FreeBSD.org .
